#%RAML 1.0
title: Login
version: v1.1
baseUri: http://github.com/org/folio/mod-auth/login_module

documentation:
  - title: mod-login API
    content: This module provides a username/password based login mechanism for FOLIO credentials

types:
  credentials: !include ../../schemas/mod-login/credentials.json
  credentialsListObject: !include ../../schemas/mod-login/credentialsListObject.json
  loginCredentials: !include ../../schemas/mod-login/loginCredentials.json
  updateCredentials: !include ../../schemas/mod-login/updateCredentials.json
  errors: !include ../../schemas/errors.schema

traits:
  validate: !include ../../traits/validation.raml
  pageable:
    queryParameters:
      length:
        description: "The maximum number of results to return."
        required: false
        type: integer
        example: 10
        minimum: 1
        default: 10
        maximum: 1000
      start:
        description: "The starting index in a list of results (starts at one)."
        required: false
        type: integer
        minimum: 1
        default: 1
        maximum: 1000
  sortable:
    queryParameters:
      sortBy:
        description: "A comma-separated list of fieldnames to sort by"
        required: false
        type: string
  queryable:
    queryParameters:
      query:
        description: "A query string to filter users based on matching criteria in fields."
        required: false
        type: string
/authn:
  /login:
    post:
      description: Get a new login token
      body:
        application/json:
          type: loginCredentials
      responses:
        201:
          headers:
            x-okapi-token:
          body:
            application/json:
              type: loginCredentials
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /update:
    post:
      description: Self-update existing credentials
      body:
        application/json:
          type: updateCredentials
      responses:
        204:
          description: "Successful update"
          body:
            text/plain: !!null
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        401:
          description: "Unauthorized"
          body:
            text/plain:
              example: "Unauthorized"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /credentials:
    get:
      description: Get a list of user credentials
      is: [
        pageable,
        sortable,
        queryable
      ]
      responses:
        200:
          body:
            application/json:
              type: credentialsListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new login to the system
      is: [validate]
      body:
        application/json:
          type: loginCredentials
      responses:
        201:
          body:
            application/json:
              type: credentials
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{id}:
      get:
        description: Get login credentials for a single user
        responses:
          200:
            body:
              application/json:
                type: credentials
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify a user's login credentials
        body:
          application/json:
            type: loginCredentials
        responses:
          200:
            body:
              application/json:
                type: loginCredentials
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a user's login credentials from the system
        responses:
          204:
            body:
              text/plain: !!null
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description:
              "Internal server error"
            body:
              text/plain:
                example: "Internal server error"


